home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / boss / boss_doc.lzh / WN_PDOWN.DOC < prev   
Text File  |  1992-03-08  |  18KB  |  468 lines
  1. PDMENU AND PDITEM DATA STRUCTURES:
  2.  
  3.  
  4. The heart of the pulldown menu system is the menu structure pdmenu. Each
  5. menu has its own pdmenu structure which describes the menu.
  6. The structure is defined in WINBOSS.H.
  7.  
  8.   struct pditem {                    /* PULLDOWN menu item template */
  9.     int r;                           /* row in menu window for item */
  10.     int c;                           /* col in menu window for item*/
  11.     char *t;                         /* menu item text */
  12.     char hkc;                        /* the menu HotKey*/
  13.     int status;                      /* item status - active/in-active */
  14.     char type;                       /* item type, action, toggle,etc. */
  15.     int rv;                          /* item return value */
  16.   };
  17.  
  18.   struct pdmenu {                    /* PULLDOWN menu structure */
  19.     WINDOWPTR wpsave;                /* menu's window pointer */
  20.     int wa;                          /* window attribute */
  21.     int ba;                          /* border attribute */
  22.     int hka;                         /* hot key attribute */
  23.     int winopn;                      /* window is open flag */
  24.     int lndx;                        /* last index selected */
  25.     int fm;                          /* first menu item index */
  26.     int lm;                          /* last menu item index */
  27.     struct pditem item[WN_MXROWS*4]; /* a bunch of menu items */
  28.   } WNPD, *WNPDPTR;                  /* NOTE RELATIVE LIMIT */
  29.  
  30. The structure pditem is modelled on the structure pitem but has several
  31. new fields.
  32.  
  33. The MENU HOTKEY is any letter in the menu text. The key is highlighted in
  34. a menu display and pressing this key will immediately select the menu
  35. item. The hotkey must have the same case (upper/lower) as its
  36. corresponding letter in the menu text.
  37.  
  38. The STATUS field defines whether a menu item is active (1) or inactive (0).
  39. Active items have their hotkeys highlighted and can be
  40. selected by the user. Inactive menu items do not have their hotkey
  41. highlighted and cannot be selected by the user.
  42.  
  43. The TYPE field holds a interger which defines the item's type.
  44. Currently, there are 5 types available.
  45.  
  46.    PDACTION - the item is an Action item. That is, selecting it will
  47. invoke some action. Load, Save, Print are examples of Action items.
  48.  
  49.    PDSELECT - an Action item that has been Selected. A program can use the
  50. routine wn_pdtype to switch an PDACTION item to a PDSELECT item to signal
  51. other parts of the program that the item has been selected. 
  52. For example, before a program prints, it can check the Load option to
  53. see if the user has loaded any data.
  54.  
  55.    PDBAR - this type is only used in a bar menu. It means that the item does
  56. not have an associated pulldown menu.
  57.  
  58.    PDTOGG - the item is a toggle. That is, selecting it simply toggles the
  59. item ON and OFF.
  60.  
  61.    PDETOGG - the item is an EXCLUSIVE toggle. Only one exclusive type toggle
  62. in a menu can be ON. Turning one ON turns another OFF.
  63.  
  64. The RV field is the items return value.
  65.  
  66. PULLDOWN MENU ROUTINES:
  67.  
  68. The wn_pd pulldown system uses 10 routines which are briefly described
  69. here.
  70.  
  71. wn_pdopen - opens a menu window if it is not yet open. Displays all the
  72. menu items. The menu can be displayed as inactive or active. An active
  73. menu has its item hotkeys highlighted. The only menu that would normally
  74. be displayed as inactive would be the main bar menu.
  75.  
  76. wn_pdclose - closes a menu window.
  77.  
  78. wn_pdupdate - displays a specified item in normal or reverse video.
  79. Primarily used by wn_pdget to indicate the current menu item being
  80. pointed to.
  81.  
  82. wn_pdgettog - this routine has two uses. If it is supplied with a menu
  83. item's return value (rv), it returns TRUE if the toggle is ON or FALSE if the
  84. toggle is OFF. If it is supplied with a value of -1 instead of a return
  85. value, it returns PDTOGOK if all menu toggles are OFF or the return value of
  86. a toggle that is ON. The -1 option is primarily used to determine which, if
  87. any, of a set of EXCLUSIVE toggles (mutually exclusive toggles) is ON.
  88.  
  89. wn_pdsettog - primarily used by wn_pdget to reverse the state of a toggle
  90. when the user selects a toggle menu item. If the toggle is an exclusive type 
  91. and it has been turned ON, the routine turns OFF all other toggles in the
  92. menu and returns the menu item INDEX of a toggle that was previously ON.
  93. If none were ON, it returns PDTOGOK. 
  94.  
  95. wn_pdactive - this routine takes a menu option's return value and
  96. activates or de-activates the menu option based on the value of a second
  97. argument. A program can use this routine to control which options a user
  98. has available at any particular point in the program. This is one of
  99. the systems most powerful features.
  100.  
  101. wn_pdtype - this routine serves two purposes. It can change the type code
  102. of a menu item or return its current type code. This routine should only
  103. be used to change type Action or type Selected or the reverse.
  104. It's primary use is to let the type code serve as a flag that can be
  105. tested to see if an item has been selected or not. As an example, the
  106. code that exits a program can check the Load and Save menu items, if Load
  107. has been selected, but Save has not, then it should ask the user if he
  108. wants to save his data before exiting the program. NOTE: the system does not
  109. automatically switch an Active type to a Selected type when an item is 
  110. selected. It is the program's duty to do this. 
  111.  
  112. wn_pdget - this is the real work horse. It gets the user's menu choice
  113. and returns the item's return code. A menu must be opened using wn_pdopen
  114. BEFORE calling this routine. wn_pdget first displays the current choice
  115. in reverse video. If all items in a menu are inactive, none are
  116. highlighted. It then waits for the user to make a selection using the
  117. arrow keys and ENTER or by pressing an item's hotkey. If the selected
  118. item is not a toggle, the item's return code is returned. If it is a
  119. toggle, its state is reversed, but the routine does not exit. If the user
  120. presses ESC, the routine closes the menu window and returns 99.
  121. Wn_pdget handles pulldown menus in a special way. When in a pulldown,
  122. pressing the left arrow key returns 97 and pressing the right arrow key
  123. returns 98. In both cases, the window is closed. The application program
  124. can use these codes to take special action. The program PDDEMO
  125. demonstrates one way of handling these codes by immediately activating
  126. the adjacent main bar menu item and displaying its pulldown. In this way,
  127. once a user has pulled down one menu, he can look at all the other
  128. pulldown menus simply by pressing the left and right arrow keys. 
  129.  
  130. wn_border - this is a handy little routine to select a single or double
  131. ruled border for all subsequent windows.
  132.  
  133. wn_drawborder - this routine immediately redraws the border of a
  134. specified window as single or double ruled.
  135.  
  136.  
  137. THE PDDEMO PROGRAM:
  138.  
  139. As well as giving a good demonstration of the power of the system, this
  140. program contains the basic code to implement almost all common menu
  141. activities and one or two less common ones. As such, it can serve as the
  142. basis for implementing your own menu system, probably with only minor
  143. changes and the addition of routines that implement the actions of the
  144. various menu items.
  145.  
  146. The look and contents are based on the menus found in many Microsoft
  147. applications such as QuickBasic, QuickC, Windows and Excel. 
  148.  
  149. The one thing where PDDEMO differs markedly from MS is in the key that
  150. activates the main bar menu. I've used the slash key (like Lotus 123)
  151. rather than the ALT key. 
  152.  
  153. PDDEMO contains examples of toggle items (Setup/Color), exclusive toggles
  154. (Setup/Printers), activating and de-activating menu options and even a
  155. neat example of how turning ON a toggle in one menu, de-activates the
  156. same option in another menu. Try selecting the same item for both the X
  157. and Y axis using the View/Graphics option. Two level and three level
  158. nested menus are also demonstrated. Most of the pulldown menus are
  159. 'single shot' menus. That is, you make a selection and then you are
  160. returned to the main program. A couple are 'sticky' menus that allow you
  161. to make several selections from the sam